ShowTable of Contents
Abstract
Domino Access Services (DAS) is a family of REST APIs built into IBM Domino and available from the XPages Extension Library
on OpenNTF. The DAS data API is used to create, read, update and delete data in any Domino server application. This article describes some techniques for optimizing the performance of the data API. It assumes you already have some experience with this API. For more general information on the data API, see this reference.
Introduction
The DAS data API is designed to provide access over HTTP/HTTPS to virtually any Domino server application. When you use the data API to read a view, an individual document, or other data object, the default response often contains more data than you actually need to implement your application. Since the data API cannot infer what's important to you, it returns the maximum amount of data. Fortunately, you can often boost performance by requesting less data. It's simply a matter of adding one or more query parameters to the request URL.
One example of this is the compact parameter. This is a boolean query parameter you can use in any GET request. Consider, for example, the database collection request:
The response is a potentially large array of databases like this:
[
{
"@title": "Administration Requests",
"@filepath": "admin4.nsf",
"@replicaid": "852573910361A2F4",
"@template": "StdR4AdminRequests",
"@href": "/admin4.nsf/api/data/collections"
},
{
"@title": "Java AgentRunner",
"@filepath": "AgentRunner.nsf",
"@replicaid": "8525671400725208",
"@template": "",
"@href": "/AgentRunner.nsf/api/data/collections"
},
...
]
By default, the response include lots of white space including spaces and new line characters. This white space increases readability and is helpful when you are learning about the data API, but it's not necessary as you move your application into production. You can remove the white space from the response by adding the compact parameter to your request:
GET /api/data?compact=true
Depending on your network bandwidth and the number of databases on your server, this can reliably shave several milliseconds off the database collection response time. Best of all, the compact parameter is available for all data API GET requests.
View Read Performance
You use the view entry collection resource to read entries in a view or folder. For example, the following is a simple view read request:
GET /XPagesExt.nsf/api/data/collections/name/AllContacts
The response is an array of view entries like this:
[
{
"@href": "/XPagesExt.nsf/api/data/collections/name/AllContacts/unid/39A95ECD82D0DEB485257AB5005BFEE0",
"@link": {
"rel": "document",
"href": "/XPagesExt.nsf/api/data/documents/unid/39A95ECD82D0DEB485257AB5005BFEE0"
},
"@entryid": "1-39A95ECD82D0DEB485257AB5005BFEE0",
"@unid": "39A95ECD82D0DEB485257AB5005BFEE0",
"@noteid": "5D26",
"@position": "1",
"@read": true,
"@siblings": 10000,
"@form": "Contact",
"Id": "CN=Aaron Goodman/O=renovations",
"FirstName": "Aaron",
"LastName": "Goodman",
"EMail": "aaron_goodman@renovations.com",
"City": "Philadelphia",
"State": "PA",
"Created": "2012-11-13T16:44:50Z",
"$10": "Aaron Goodman"
},
{
"@href": "/XPagesExt.nsf/api/data/collections/name/AllContacts/unid/32898140B9DB45F485257AB5005A9394",
"@link": {
"rel": "document",
"href": "/XPagesExt.nsf/api/data/documents/unid/32898140B9DB45F485257AB5005A9394"
},
"@entryid": "2-32898140B9DB45F485257AB5005A9394",
"@unid": "32898140B9DB45F485257AB5005A9394",
"@noteid": "D7E",
"@position": "2",
"@read": true,
"@siblings": 10000,
"@form": "Contact",
"Id": "CN=Aaron Guerrero/O=renovations",
"FirstName": "Aaron",
"LastName": "Guerrero",
"EMail": "aaron_guerrero@renovations.com",
"City": "Coral Springs",
"State": "FL",
"Created": "2012-11-13T16:29:20Z",
"$10": "Aaron Guerrero"
},
...
]
By default, the response includes the first page of 10 entries. You can increase the page size (e.g. count=50) and send subsequent requests for more pages (page=1, page=2, etc.).
Prior to Domino 9.0.1 FP8, there was virtually no limit to the number entries you could ask for in a single request. If the view had tens of thousands of entries, you could receive ten thousand (count=10000) or more entries in one response. However, as of Domino 9.0.1 FP8, the maximum pages size is 100 entries by default. IBM made this change in response to problem reports citing poor performance when the server was handling hundreds of simultaneous requests for ten thousand or more rows of data. Since the data API was never designed to support that kind of load, IBM decided to enforce a maximum page size. This encourages paging through large views and improves overall performance.
NOTE: We realize this change in behavior has the potential to break existing applications. You can relax the page size limit with a server Notes.ini setting. For example, use the following setting to increase the maximum page size to one thousand entries:
DataServiceMaxViewEntries=1000
For best performance under high load, it's best to keep the maximum page size as low as possible.
Of course when optimizing performance, the size of each entry may matter as much as the total number of entries in each page. Referring to the sample response at the beginning of this section, you will notice two distinct kinds of properties for each entry. There are system columns (@href, @link, @unid) -- the names of which each begin with an @ -- and there are application-specific properties (Id, FirstName, LastName, etc.). By default, the response includes all available system columns, but you can improve performance by using the systemcolumns parameter.
Consider a request like this:
GET /XPagesExt.nsf/api/data/collections/name/AllContacts?systemcolumns=0
The response is similar to the previous example, but most system columns are excluded:
[
{
"@entryid": "1-39A95ECD82D0DEB485257AB5005BFEE0",
"Id": "CN=Aaron Goodman/O=renovations",
"FirstName": "Aaron",
"LastName": "Goodman",
"EMail": "aaron_goodman@renovations.com",
"City": "Philadelphia",
"State": "PA",
"Created": "2012-11-13T16:44:50Z",
"$10": "Aaron Goodman"
},
{
"@entryid": "2-32898140B9DB45F485257AB5005A9394",
"Id": "CN=Aaron Guerrero/O=renovations",
"FirstName": "Aaron",
"LastName": "Guerrero",
"EMail": "aaron_guerrero@renovations.com",
"City": "Coral Springs",
"State": "FL",
"Created": "2012-11-13T16:29:20Z",
"$10": "Aaron Guerrero"
},
...
]
Depending on the view design, this can reduce the size of the response by more than 50%. Not only does it take less time to transfer the response across the network, but the server spends less time reading data from the underlying view -- data you may not need any way.
The value of the systemcolumns property is actually a bit mask where each bit represents a specific system column:
- @noteid -- 0x0001
- @unid -- 0x0002
- @position -- 0x0004
- @read -- 0x0008
- @siblings -- 0x0010
- @descendants -- 0x0020
- @children -- 0x0040
- @indent -- 0x0080
- @form -- 0x0100
- @category -- 0x0200
- @response -- 0x0400
- @href -- 0x0800
- @link -- 0x1000
- @score -- 0x2000
So to request the @unid property and no other system columns, you might send a request like this:
GET /XPagesExt.nsf/api/data/collections/name/AllContacts?systemcolumns=0x0002
Or to request just the @unid and @link properties, you might send a request like this:
GET /XPagesExt.nsf/api/data/collections/name/AllContacts?systemcolumns=0x1002
In other words, you can request just the set of system columns you need for your particular application.
Document Read Performance
Conclusion